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ABSTRACT 


This paper describes the user interface strategy of Document Examiner, a delivery interface for 
commercial hypertext documents. Unlike many hypertext interfaces, Document Examiner does 
not adopt the directed graph as its fundamental user-visible navigation model. Instead it offers 
context evaluation and content-based searching capabilities that are based on consideration of 
the strategies that people use in interacting with paper documents. 


INTRODUCTION 


Hypertext documents are linked modules of information, created, distributed, and accessed 
electronically! 2. This technology has tremendous potential for making more information 
more available to more people. The challenge at this time is to make the information ac- 
tually accessible to people, not just potentially accessible. That is, the major challenge lies in 
defining the user interfaces for the software that will deliver hypertext documents. 


Interfaces for most research-oriented hypertext systems have reflected the organizational 
structure of the underlying hypertext document. That is, the information base was or- 
ganized as a network; the user interface was organized as a network browser®*. A solely 
network-based interface is not, however, a necessary characteristic of a hypertext document. 
It might not even be a desirable characteristic, once the time comes for hypertext to leave the 
shelter of academic research environments. 


This paper describes the user interface strategy used in Document Examiner, an end-user 
interface for commercial hypertext documents®. Document Examiner is part of Symbolics 
Genera®, the software development environment (operating system) for Symbolics com- 
puters. 


The examples in this paper show Document Examiner being used to deliver the Symbolics 
software product documentation. In printed form, this documentation consists of around 
8000 pages. It contains all forms of documentation, from initial tutorial material to reference 
material on software internals. This documentation was prepared by technical writers as 
part of the Symbolics software product. 


In order to set the context, I would like to outline some of the factors for categorizing hyper- 
text systems and contrast our system with two typical, widely known hypertext systems, 
Xanadu’ and NoteCards?: 
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¢ What does it hold? We deliver documentation that is part of a larger software product. 


Xanadu was designed to manage a library of prepublished material, Notecards to or- 
ganize a set of working notes. 


e How is it organized? Our documentation is highly structured. The material in library- 
like systems has few inherent interrelationships. The material in Notecards is highly 
interrelated but typically not highly structured. 


© Who writes it? Our document is prepared by a small group of cooperating writers. The 
documents in Xanadu were to be submitted by authors and the annotations by readers; 
in Notecards, each user serves as both writer and reader (although recent work® has 
explored using Notecards for collaborative work. 


¢ How much does it change? Our document is under constant maintenance, with revised 
versions published with every software release. It has more changes than a library but 
is more static or controlled than the information in Notecards. 


¢ How big is it? Our documentation corresponds to 8000 printed pages with about 
10,000 nodes and 23,000 links. This is small by "global library” standards but large in 
comparison to personal notes. 


e Where does it fit in? This work has commercial rather than academic roots and 
production rather than research goals. 


Many current hypertext systems are research vehicles developed in academic environments 
where it is feasible to have individuals assuming both writer and reader roles interchange- 
ably. In fact, some hypertext systems offer a common interface for reading and writing. In 
the product development world, however, it is more conventional and manageable to 
separate these roles: the writers are product developers and the readers are customers. We 
have separate interfaces for reading and writing our documentation. This paper addresses 
the readers’ interface only, leaving description of the writers’ issues to other papers” 10,11. 


DOCUMENT STRUCTURE 


This section describes the documentation database for which Document Examiner is the 
interface. 


The documentation is organized as a database of modules. The writers determine the nature 
of the modularity, depending on the information needs of the subject they are documenting. 
Modules can be any size at all and can contain any kind of subject matter. The decisions are 
made by the writer and are not subject to any kind of enforcement. Writers choose the 
module boundaries according to their understanding of how readers will need to access the 
material. 


Modularity 


In our implementation, we refer to the modules as records. Each record in the document 
database has a unique identifier, assigned at the time of its creation. These identifiers are 
used internally by the system to track the location of records. Readers and writers specify a 
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record by its name and type. Names are just that: any words sufficient to name the topic 
uniquely (within its type). Because our application is software documentation, the types are 


things like "function", "variable", or "section". 


Internally, each record is composed of fields, which embody various kinds of information 
about the record: 


e Content fields for the document (full description, one-line description and so on). 
e Accessory information (keywords, the record type and so on). 

e Audit information (the version number and the publication status of the record). 
e Database information (the server location of the record, its outward links). 


Figure 1 diagrams the kind of information found in a typical record. The content and acces- 
sory fields are maintained by the writers; the others are maintained by the editor that the 
writers use and by other supporting software. 


Field name Field contents 


Name: DOC: |CONVERSATION COMMANDS | 

Version-number: 1 

Disk-location: (#P"Q:>rel-7>sys>doc>conv>convl.sab.18" 6328 7780) 

Source-file: "SYS :DOC;CONV; CONV1L.SAR.36" 

Contents: #<RECORD-FIELD CONTENTS> 

Children: ( (INCLUDE 
#<RECORD-GROUP DOC: |APPEND CONVERSATION COMMAND | > 
#<RECORD-GROUP DOC: |DELETE CONVERSATION COMMAND |> 
#<RECORD-GROUP DOC: ]WRITE CONVERSATION COMMAND |>) ) 


Tokens: (("Converse"™ “commands") ) 

Keywords: #<RECORD-FIELD KEYWORDS> 

Oneliner: #<RECORD-FIELD ONELINER> 

Source-topic: #<RECORD-FIELD SOURCE-TOPIC> 
Source-type: SUBSECTION 

Flags: Available, Modified, Filled, Installed 
Modification-history: ((1 “jwalkexr™ 2760810574) ) 


Figure 1: A representation of a record data structure, showing some of its fields and their contents. 


Relationships 


One of the fundamental characteristics of a hypertext document is modularity. Another such 
characteristic is the ability to indicate the relationships between the modules. The hypertext 


literature often describes these relationships as "links"!. 


In our database, the writers use links between records to establish the overall structure of 
the documents in the database (see Figure 2). The links are directional, from one record to 
another. Links can link whole records or link a point in text to a whole record. In practice, 
in the current documentation, all of links are from a point to a whole record. 
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Figure 2: Links from a point in one record to another record. 


In a documentation application, it is necessary to impose some structure on the information 
rather than providing simply a large "flat" namespace of interrelated modules. You can 
think of a conventional document, containing chapters, sections, subsections, and so on, as 
being a predefined path through a hypertext structure. The writers use links from within 
the textual content of a record in order to impose structure on the modules and hence create 
the document structure. 


A taxonomy of different kinds of links has been proposed by Trigg!?, At this time, we have 
only one kind of link and we support several different kinds of views for it: 


e Inclusion. An inclusion link specifies that the content fields of the record referred to 
are to be included at that location when a reader is reading the document. 
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e Precis. A precis link specifies that the title and oneliner fields of the record are to be 
included at the location of the link. 


e Crossref. The result of a crossreference link is to insert a conventional crossreference 
at the location of the link, for example, "See the section Combatting Gnats." 


Implicit. As writers create the material, they can enclose the names of some topics in 
implicit name links. 


Conventional document structures are built using these different record views. One record 
can "call" any other record using a link. Figure 3 shows the structure imposed by inclusion 
and crossreference links on a set of records. 


Show 
Section A 


Document Database 


Show 
Section G 


See also D 


See also B 


Figure 3: Paths through the database. The names of the nodes are letters A through G. The links 
between the nodes are the arrows, labelled with I to indicate inclusion and r to indicate a crossreference. 
The figure diagrams the results of two documentation lookups, for nodes A and G. 


November 1987 Hypertext '87 Papers 311 


312 


Versions 


Some hypertext systems incorporate concepts that are usually addressed under the topic of 
version control or configuration control in software development systems!*, This is primarily 
a document structure or management issue as opposed to an interface issue. For configuring 
the document, our document database uses the general system configuration tools!4 avail- 
able with Symbolics Genera. In addition, writers can view either the published version of a 
record or the version(s) they are currently working on. 


INTERFACE REQUIREMENTS FOR HYPERTEXT DOCUMENT DELIVERY 


Hypertext documents, hypertext delivery software, and hypertext authoring software are al] 
distinct, separable problems. In most cases so far, the people building the delivery interface 
are also the people creating the underlying information structure that it is delivering. Hence 
it is natural, but not necessary, for these three components to become intertwined in design. 
As the concepts in this field mature, this situation will change; standards for information 
structures will emerge, companies will emerge to prepare documents in hypertext form and 
other companies will develop delivery interfaces to serve different customer bases. (Apple’s 
HyperCard product is a preview of the future in information delivery.) 


In the near term, the problem facing designers of hypertext delivery interfaces is exactly that 
posed by Jeff Conklin in his description of using hypertext!: 


"The writer is no longer making all the decisions about the flows of the text. The 
reader can and must constantly decide which links to pursue....reading hypertext 
... tends to present the user with a large number of choices about which links to 
follow and which to leave alone. These choices engender a certain overhead of 
metalevel decision making..." 


This is a description of a very high level of cognitive overhead, much higher than that ex- 
perienced by people reading conventional documents. I think we should view this description 
as the challenge of hypertext interface design rather than as its solution. 


If hypertext documents are to replace paper documents, they must both retain the ad- 
vantages of paper delivery and provide the advantages of electronic delivery. 


What does a paper manual provide? 


In spite of its often-derided rigidity and linearity of structure, paper has had many incidental 
good qualities as a delivery medium. In designing a replacement for paper, one needs to 
consider these qualities and to devise electronic analogs for them. 


What do people do with paper manuals? How do they use them? 


e Look up things they know they want. They use the index to locate the relevant pages. 
For something they refer to often or something very important that they want to be 
able to find again, they put in bookmarks. 


¢ Try to find out what they want. They sometimes use the index or table of contents to 
find anything that might be related to what they want. They then travel in ever- 
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widening circles around that area of the book, hoping to stumble on the relevant 
material. 


¢ Try to find out the general nature of what is available. They use the table of contents 
to see the overall structure or generally flip through pages looking at headings or pic- 
tures. 


e Annotate the material. They use a highlighter to emphasize relevant portions. They 
make notes in margins with ideas, crossreferences, caveats, clarifications, or examples. 


e Take “snapshots” for use elsewhere. They sometimes copy pages for either remote use 
or very fast reference use. 


People also mention the reassuring tangible, physical nature of paper: 
e Take it on the bus. Books are portable; you can read them anywhere. 
e Leave it open beside the keyboard. 
e Find vaguely remembered information by position. 


e See at a glance “where” you are (by fractional position within the book). The size, feel, 
and design of a book all give information about its likely relevance to any particular 
information-finding problem. 


In addition, paper is a "low overhead" medium for readers. If they want, they can simply 
read the material in the order that it was supplied by the author, with some degree of con- 
fidence that the result was designed to be comprehensible that way. Strategies for using 
paper documents are highly overlearned skills for most adult computer users. 


Replacements for the good qualities of paper need to be more than imitations that try to 
carry the surface features of paper into the electronic world. Instead, they should be func- 
tional analogies that provide the same kinds of benefits with an entirely different implemen- 
tation. 


What can an electronic manual provide? 
An online manual can provide benefits that are unimaginable with paper delivery. 


¢ Full indexing. We can analyze the contents of electronic documents in order to provide 
much more complete indexing than is feasible for almost any paper document. In 
addition to indexing, brute-force full-text searching is also an option for locating 
material. 


© Quick following for cross-references. When the text of a document instructs its reader 
to "See section 9.3", a document delivery interface can let the user follow that instruc- 
tion directly. 


¢ Back referencing. Software that can analyze the structure of a document knows which 
other topics have links to a particular topic. 


e History. An online delivery interface can keep track of what the reader has already 
seen. 
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As online information bases become more extensive, helping users manage volume, context, 
and history will emerge as the most important practical problems with interfaces. 


DOCUMENT EXAMINER INTERFACE DESIGN 


Document Examiner was designed to preserve beneficial aspects of paper manuals while 
adding the power and flexibility of content-based operations. 


Document Examiner is a window-based utility that is integrated with the rest of Symbolics 
software environment. Figure 4 shows a screen display from Document Examiner. 


j Current Candidates 
Document Examiner Presentation Substrate Facilities 
Basic Presentation Systen Concepts 
Predefined Presentation Types 
Neta-Presentation Argunents to Presentation 
Inheritance of Presentation Argunents 
Presentation-Type Definition Facilities 
Presentation Input Context Facilities 
Presentation Input Slip Facilities 
Other Presentation Facilities 
Writing a Presentation Type Parser 
User~Defined Data Types as Presentation Types 
Exploring Presentation Types and Presentation 
Show Presentation Type Command 
Show Handlers For Types Connmend 
Presentation Inspector 
Using the Presentation Inspector 
Invoking the Presentation Inspector 
The Presentation Inspector's frane 
Strategy for Using the Presentation Ins 
Presentation Inspector Connands 
Sunmary of Presentation Inspector Conna 
Help Presentation Inspector Connand 


Predefined Presentation Types 


Presentation types form the basis of the typing system for user input 
and program output. A large number of predetined presentation types 
exist; relatively few are used for program I/O. This is because every 
structure, flavor, and Common Lisp data type is also a presentation 
type. Most, however, are of little use in end-user-oriented application 
programs. Consider, for example, the Common Lisp types hash-table 
and compiled-function; you would not generally encounter these in 
and-user-visible places. 


In this section, we list what we regard as the types most likely to be 
used by application programmers. Some, like integer, string, and 
boolean, are encountered frequently in all kinds of programs. Many 
others, like sys:code~fragment and net:network, are more 
specialized in their uses. 


In any case, all of the types Included here are also documented as 
individua! entries in the Dictionary of Predefined Presentation Types. 
Also, many of them are defined in the file 

sys: dynanic-uwindous; standard-presentat jon-types. lisp, where you 
can look for models when defining your own types. The dictionary 
entry for each type notes whether it is one of those inciuded in this 
ie, 


The documented types are divided into thres groups: 
1. Common Lisp Presentation Types 

2. Symbolics Common Lisp Presentation Types 

3. Other Presentation Types 


Of course, the Common Lisp types form a subset of the Symbolics 
Common Lisp types, but for the purposes of the present discussion, 
we separated them out. The Other Presentation Types include the 
potentiafly useful types exported from packages other than Symbotics 
Common Lisp; most of them are in the specialized-use category. 


The following table lists the useful Common Lisp presentation types: 


M.A 


Ytlfte 


Yudtiplirh til 


LL 


Bookmarks 
@ Predefined Presentation Types Section 


dttele titer lte tretitele 


dadltllnbateticlidanitites tuuthlitiing: 


Mh  eliediiluleasiintediit 


Common Lisp Presentation Types 
and 
character 


Cl WO aM 


Viewer: Standard (Reader) 
Commands Show Candidates Help 

» Show Overviev Predefined Presentation Types Show Documentation Select Viewer 

» Find Table Of Contents Presentation Substrate Facilities Show Overview Reselect Candidates 
® Show Documentation Predefined Presentation Types Show Table of Contents Private Document 
> 


Mouse-R: Menu. 
To see other commands, press Shift, Control, Meta-Shift, or Super. 


hu ict. 15:1 eyboard L | 7 ser Input 


Figure 4: Document Examiner screen display. The viewer contains the first screenful of a section, whose 
bookmark is in the bookmarks pane. The candidates pane contains the table of contents for the document 
that this section appears in. Several recent commands are visible in the command pane. 


The most fundamental decision in the interface was to make the material that a person was 
reading look essentially as it would in a paper book. The reason for doing this was "ease of 
use". We saw no reason to have the underlying information structure be reflected in the user 
interface model unless that structure was a good model for interacting with information. My 
experience in trying to help users with a tree-structured information interface (the INFO 
subsystem in EMACS) led me to believe that a book-like interface would be more palatable 
for many people. 
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The rest of this section describes the ways in which Document Examiner addresses the re- 
quirements of people using it to read documentation. 


General description and terminology 


Document Examiner is an application that runs in its own window. The window is divided 
into panes (subwindows) used for different aspects of managing the user’s interaction with 
the document: 


e Viewer. The majority of the screen area is used for showing a topic. It gives people the 
feeling of reading a section from a book. 


e Command pane. The bottom area of the screen contains a fixed command menu and a 
command interactor area where the user can type commands. Most commands are 
available in either mouse or keyboard forms. 


e Candidates pane. “Candidates" is the term used for a set of record names that have 
been retrieved in answer to some user query. Candidates are mouse-sensitive. (that is, 
clicking a mouse button while the mouse cursor is positioned over the name invokes a 
command.) 


« Bookmarks pane. This area of the screen maintains a chronological record of the topics 
that a user has read in the accompanying viewer. The bookmarks are mouse-sensitive. 


¢ Overview window. "Peephole” context for a topic. In a temporary display, the overview 
shows both a graph of the inclusion links for a topic and all its outward links. 


Topic Lookup | 


The basic lookup command is Show Documentation, which operates on a record name. This 
is the command that users issue to see documentation for some system feature or document 
section for which they already know the name (or enough of it to specify the record uniquely). 
Figure 4 shows a record partially read into a viewer. 


Show Documentation is actually a request for an inclusion view of the record. The system 
retrieves the record from the remote server and begins displaying the fields specified for an 
inclusion view. As further references are encountered, those records are retrieved and dis- 
played according to the view that the writer specified for them. Structurally speaking, the 
users are reading the linear structure resulting from tree traversal of a subtree in the docu- 
ment structure. 


Users can scroll forward through the topic to its end. Repositioning within a topic is handled 
with standard system scroll key commands and a mouse-operated scroll bar. 


The display is analogous to an editor buffer in which each new record’s display is appended 
to previous displays. The user can reselect previously displayed records (using the names in 
the bookmarks pane), scroll through earlier text, or use search commands to look for a par- 
ticular textual string within the display. 


As writers create the material, they enclose the names of topics in implicit name links. 
Figure 4 shows a record that contains this kind of link. Every topic name that is visible 
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anywhere in the documentation can be an implicit link to another topic. Users can follow 
these links because they are mouse-sensitive, either directly or as operands for typed-in com- 
mands. 


Finding topics of interest 


The basic search command is Show Candidates, which operates on a set of words. This 
command is Document Examiner’s equivalent to using an index in a paper manual. This is a 
happy case where a strategy that people are accustomed to from the paper world (using an 
index) can be implemented far more powerfully online than in the paper world. 


Show Candidates uses the word or phrase that the user specifies to search for records that 
contain those words in their titles or keywords. Figure 5 shows some results from an ex- 
ample query. 


Command line: 
Show Candidates finding help 
Candidates offered: 


Finding Out About Zmacs Commands with HELP 

Finding Out What a Prefix Command Does 

Method for Searching for Appropriate Zmacs Commands 

More HELP Commands for Finding Out About Zmacs Commands 


Keywords for "Method for Searching for Appropriate Zmacs Commands": 


m-X Apropos 

Searching for appropriate commands 
Finding the right command 

Help A Zmacs command 


Figure 5: Documentation topics suggested by Show Candidates for the words “finding” and “help”. 


The user can control several attributes of the search strategy: 


e Kind of matching. The default search strategy uses simple heuristic matching to iden- 
tify records of interest. When the words in the query and the words in the keywords 
have stems!5 in common, then the record is retained for the candidates. For example: 
"Deleting files” matches delete-file 


File deletion 
Deleting multiple file versions 


Also available are other modes of searching that involve conventional exact or substr- 


ing matching on the query words and keywords. 


¢ Multiple word order. The default is to accept a record as a candidate if it has the query 
words in the keyword phrases in any order. Other modes specify that the words have 
to be adjacent, in the same order, or nearby (in the same keyword phrase) in order for 
the record to qualify. 
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e Word combination. The default searching uses “logical and" combination for a multiple 
word query. All of the words in the query have to be present in the keywords for the 
record to be a candidate. 


Searching is based on keywords rather than the full text of the documentation for several 
reasons. Full-text searching is slower than keyword search by definition because the volume 
of material is much greater. In addition, the full text is kept on a server machine (for storage 
efficiency) rather than in the user’s local memory; searching would be a performance bot- 
tleneck when several users needed to search at once. Furthermore, although we have not 
tried a fully inverted index, we expect that it would result in many more false alarms with- 
out more hits than keyword indexing does. 


The candidates resulting from any query are stored in the candidates pane. Figure 6 shows 
the candidates list that results from a search for "deleting files". Any record in the can- 
didates pane can be operated on with a number of mouse commands, including: 

Show Documentation 


Show Overview 
Show Table of Contents 


Document Examiner 


Current Candidates 
Delete File 

Delete File Command 

DELETE-FILE 

Deleting Files 

Deleting Multiple File Versions in Dired 

FEP File Properties 

FS: DELETE-FAILURE 

How to Interpret Directory Listings 
Performing Dumps 

Protecting Files From Being Deleted in Dired 
Saving the Mail File 

SI: COM-DELETE-FILE 

Using FSEdit Commands 

UCI: : DELETE-ENCACHED-F ILE-BRANCH 

ZL: DELETEF 


Le 


ars rhianllalyalicaggllintyiiidllatititidtila 


Vir ob ithe tilin adipsia ts ieMllsilillliiiitt ly thelial dithsadleride ie rmnsdiieddlaiMdidintis Wl 


(OL 


Viewer: Standard (Reader ) 


Commands Show Candidates Help 
Show Documentation Select Viewer 
Show Overview Reseiect Candidates 


Show Table of Contents Private Document 


Show Candidates (word(s) Cdefault “presentation types"}) deleting files 
a 


Mouse-L: Show Documentation; Mouse-M: Overview; Mouse-R: Menu. 
To see other commands, press Shift, Control, Control-Shift, Meta-Shift, or Super. 
Utho @ Oct 12:30:31] jualker CL-USER: User Taput 


Figure 6: The candidates pane contains the list of candidates resulting from the search for "deleting files”. 
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Examining context and structure 


After using an index search command, the user next needs to determine which of the items 
retrieved are most relevant. Using an index in a paper manual, this can be a very time- 
consuming task, depending on the quality of the index and the number of references to check. 
In this arena, an online system can shine. 


The Show Overview command displays an overview of any record (see Figure 7). An over- 
view contains contextual information enabling the user to determine whether or not this 
record is relevant and, if it is relevant, whether it or something related to it is more ap- 
propriate. 


Current Candidates 
Append Conversation 


Document Examiner 


(n-K) Converse Connand 
append conversation by references (m-K) Znail C 
Delete Conversation (m-X) Converse Connmand 
delete conversation by references (m-K) gmail C 
Introduction to Converse 

Replying to Znail Messeges 

select all conversations by references (m-X) Zn 
select conversation by references (m-K) Znailt C 
Write Conversation (n-X) Converse Conmand 


Overview 
Section: “Using Converse’ 
It Is Included In topics: “Converse®, “Talking to other Users* 


It appears in documents: Communicating With Other Users, User’s Guide 
to Symbolics Computers 


Keywords: 
Sending Interactive Messages 


See also: 
“Customizing Converse® 


Introduction to Converse ending and Replying to Messages with Conver i 
ett Sree one Behavior of Converse 
introduction to Converse onverse Commands 
sp Listener Commands for Converse 


ending and Replying to Messages with Conver 


Talking to other ee 


efault Behavior of Converse 
onverse Commands 


Converse. sing a 
ustomizing a 


isp Listener Commands for Converse 


Viewer: Standard (Reader) 


Show Candidates Help 


mands 
Shou Candidates (uord(s) [default “deleting files"]) conversations 
wR Show Iverview Zatroduction to Coaverse 
» Show Overview Using Converse 


Select Viewer 
Reselect Candidates 
Private Document 


Show Documentation 
Show Overview 
Show Table of Contents 


Mouse-R: Menu. 
To see other commands, press Shift, Control, Meta-Shift, or Super. 


hu ct 12: jue =U! ser Input 


Figure 7: An overview for the section "Using Converse" appears in a temporary window overlaying the 
Viewer. This section occurs twice in the document set, in two contexts, as shown by the diagram. 


One graphic display is shown for each inclusion-type link to the record. In tree structure 
terms, the graph shows the parent, siblings, and children for the overviewed record. All of 
the record names on the screen are mouse-sensitive so that the user can explore this set of 
topics further, perhaps with more overviews, in order to pinpoint the relevant areas of the 
document. In fact, users employ the overview heavily to explore "the neighborhood" for a 
record and thus to zero in quickly on the most relevant area to read. This graphic display is 
primarily a decision-making aid and only secondarily a navigation aid. 
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This kind of display has significant advantages over either a conventional table of contents 
or a full display of the graph. It constrains the amount of information that the user has to 
process while still giving enough relevant information with which to make decisions. (In this 
sense, it is similar to the powerful "fisheye view” concept!®.) 


Users starting out to investigate a new system or new topic area need an equivalent to the 
paper-based strategy of flipping pages to see what’s there. To address this need, Document 
Examiner can provide a table of contents for the subtree under any record. Figure 4 has a 
table of contents display in the candidates pane. 


The initial screen display (Figure 8) has the names of all the documents in the document set 
so that the reader can use those as a basis for commands to see either an overview or their 
table of contents. 


Current Candidates 
Site Operstions 
User's Guide to Synbolics Computers 
Synbolics Common Lisp: Language Concepts 
Synbolics Connon Lisp: Language Dictionary 
Text Editing and Processing 

Progran Developnent Utilities 

Reference Guide ta Streans, Files, and Iva 
Communicating with Other Users 

Progranning the User Interface, VolTune A 
Progrannming the User Interface, Volune B 
Internals, Processes, and Storage Managenent 
Netuorks 

Syeten Index 

Genera ?.@ Release Notes 

Genera 7.1 Patch Notes 

Genera 7.2 Release Notes 

Converting to Genera 7.6 

Symbolics IP/TCP Software Package 

Synbolics Bigital Network Architecture (DNA) So f 
Statice 

Symbolics Internal Guide to Version Contro} 
Symbotics Version Control Design and Inplementa 


Document Examiner 


VLMa 


WLU ALG 


hte 


Wh 


iriiatle 
ZZ 
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WL 


BMI UU Rta 


CELL LM LE kak 


Viewer: Standard (Reader) 


Show Candidates Help 


iS 
» Show Qverviev Using Converse 


Show Documentation Select Viewer 
® Space Renove Typeout Nindov Show Overview Resetect Candidates 
4 Select Candidates List 5 Show Table of Contents Private Document 


Mouse-R: Menu. 
To see other commands, press Shift, Control, Meta~Shift, or Super. 
[Tho 8 Oct 12:58:51] Keyboard CL-USER: User Trput 


Figure 8: Initial screen configuration of Document Examiner, showing the “top level” directory of docu- 
ments. 


Saving the results of an investigation 


Users shouldn’t have to remember the history or state of their interaction with a document. 
Document Examiner addresses the issues of convenience and memory load with both short- 
term and long-term strategies. 
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For assistance with an ongoing investigative session, Document Examiner maintains several 
kinds of context: 


e Input history. Using a standard system feature in Symbolics Genera, the user can 
recapture and edit any command entered earlier in a session. 


¢ Query result history. In addition to reactivating earlier commands, a user can select 
the results of earlier commands. For example, the results of earlier queries can be 
reinstated in the candidates pane, saving some time but more importantly, eliminating 
the need for users to remember their exact queries. 


e Lookup history. When a user asks to see a record, Document Examiner creates a 
bookmark for it. The set of bookmarks in the bookmarks pane constitutes a chronologi- 
cal record of a user’s interactive session. The bookmarks are active, of course, so that a 
user can reselect a topic by clicking the mouse over the topic’s bookmark. 


e Reading context. Users follow crossreference links freely, suspending reading one topic 
in order to look at another. Document Examiner saves the user’s reading position 
within a topic so that when they reselect that topic, it is positioned as they left it. 


e Preserving lookup history. When substantial effort has gone into finding a set of 
relevant topics, it is useful to be able to save the results of this effort for a future 
session. The user can save a set of bookmarks in a file called a “private document”. 
The set of topics represented by the bookmarks can then be read in automatically in a 
subsequent session. This is our approach to the need addressed by Bush’s “associative 


trails" in Memex!”, 


EVALUATION 


Document Examiner attempted to provide users with familiar and functional] strategies for 
finding and using information in a large document set. How well did it succeed? 


e Look up things you know you want. Show Documentation displays exactly and only the 
topic that the user requests. 


e Try to find out what you want. Show Candidates functions like a powerful index. 
Show Overview displays local context and acts as a decision-making aid for whether to 
read a topic. 


e Try to find out the general nature of what is available. Show Overview and Show Table 
of Contents display local or complete structural information for a document. 


e Annotate the material. We have not yet attempted to address this issue. 


e Take snapshots. Several commands serve to hardcopy a record or collection of records. 
Save Private Document lets the user save a collection of bookmarks for future use. 
Users can copy areas of the viewer (for example, code fragments) to editor buffers for 
further manipulation. 


e Tangible aspects of paper. Document Examiner has a full-screen window whose parts 
are stable and always visible. Although this by no means models the physical at- 
tributes of paper, subjectively it has some similar reassuring properties. 
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Document Examiner was first shipped as part of Symbolics software product in April of 1985. 
In our experience, it is both usable and used. In a year-long usage survey, we found users at 
all levels of experience used Document Examiner about equally often. Both groups of users 
looked up large "conceptual" topics as well as short reference ones; Show Overview and Show 
Candidates commands were used heavily for locating material to read!8, 


New employees of Symbolics are introduced to Document Examiner as part of their early 
experience with the machine. We have software engineers who know little about the or- 
ganization of the paper manuals as they do most of their reading using the online form of the 
manual. In fact, a recent survey of the engineering staff found about half of the 24 people 
who answered either did not have a paper document set or had not removed the shrink wrap 
from their books (five months after receiving them). 


Several people expressed strong preference for online lookup over paper. One person men- 
tioned using paper occasionally when they didn’t understand something reading it online 
(but commented that "the documentation was as impenetrable on paper as it was [online].”) 
A few people remained opposed to online information delivery in principle, independent of 
the interface. For these people, the subjective value of the tangibility of paper outweighs all 
current benefits of electronic delivery. 


The major complaints concerning Document Examiner, from both customers and inhouse 
users concern performance. Many commands, including overviews, large tables of contents, 
long lists retrieved by index searching, and remote lookup of long topics, take more than 10 
seconds to complete. This amount of delay is unacceptable to everybody, including the im- 
plementors. The fact that people do continue to use this facility heavily in spite of the delays 
is probably a testimony to the usefulness of the online features over paper. 


ISSUES FOR FURTHER WORK 


We have identified a number of areas in our implementation that need further investigation: 


e Locators. As the documentation being delivered by this kind of interface becomes 
larger, the index searching capabilities become correspondingly more important. Some 
of the work now underway in information science in automatic indexing is relevant to 
hypertext document delivery (for example!%). 


e Annotation. As in other hypertext implementations, users do need the capability to 
make notes "on" our documentation. We have approached this problem cautiously, 
however, since the design issues include helping users maintain their notes across 
different releases of the system documentation. 


e Context. Readers often have some need to constrain the set of topics under considera- 
tion in searching tasks. Several kinds of constraints: 


* Structural. Consider only one particular document (that is, the records in a 
particular subtree). 


¢ Content. Consider only records that have anything to do with some general topic 
area (for example, only records related to I/O). 


This issue has been addressed by Intermedia with the concept of webs22, 
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e Naming. Our topics are designated externally by topic/type identifiers. This naming 
strategy requires that topic names be unique within their type. At present, "section" is 
the record type used for all conceptual material in documents. As a result, the writers 
often feel that their freedom to name things appropriately is hampered by the im- 
plementation. 


CONCLUSION 


Document Examiner meets its goals of delivering information from a large, complex docu- 
ment set to users. As an interface to information, it is flexible and powerful. By building the 
interface around the information-finding knowledge and strategies that people bring from 
their experience with paper documents, it is simple to operate. 
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